.TH std::ranges::cbegin 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::ranges::cbegin \- std::ranges::cbegin

.SH Synopsis
   Defined in header <ranges>
   Defined in header <iterator>
   inline namespace /* unspecified */ {

       inline constexpr /* unspecified */ cbegin = /*      \fI(since C++20)\fP
   unspecified */;                                         (customization point object)

   }
   Call signature
   template< class T >

       requires /* see below */                            \fI(since C++20)\fP

   constexpr /* see below */ auto cbegin( T&& t );

   Returns an iterator to the first element of the const-qualified        (until C++23)
   argument.
   Returns a constant iterator to the first element of the argument.      (since C++23)

   range-begin-end.svg

   Let CT be

     * const std::remove_reference_t<T>& if the argument is an lvalue (i.e. T is
       an lvalue reference type),                                                (until
     * const T otherwise.                                                        C++23)

   A call to ranges::cbegin is expression-equivalent to
   ranges::begin(static_cast<CT&&>(t)).
   If the argument is an lvalue or
   ranges::enable_borrowed_range<std::remove_cv_t<T>> is true, then a call to
   ranges::cbegin is expression-equivalent to:

     * std::const_iterator<decltype(U)>(U) for some expression U equivalent to   (since
       ranges::begin(/*possibly-const-range*/(t)).                               C++23)

   In all other cases, a call to ranges::cbegin is ill-formed, which can result
   in substitution failure when the call appears in the immediate context of a
   template instantiation.

   The return type models std::input_or_output_iterator
   and constant-iterator
   (since C++23) in all cases.

.SH Notes

   For an lvalue range e of type T, ranges::cbegin(e) is equivalent to

   ranges::begin(std::as_const(e)).                                       (until C++23)
     * ranges::begin(e) if T models constant_range.
     * Otherwise, ranges::begin(std::as_const(e)) if const T models       (since C++23)
       constant_range.
     * Otherwise, std::basic_const_iterator(ranges::begin(e)).

.SH Example


// Run this code

 #include <cassert>
 #include <ranges>
 #include <vector>

 int main()
 {
     std::vector v{3, 1, 4};
     auto vi = std::ranges::cbegin(v);
     assert(3 == *vi);
     ++vi; // OK, constant-iterator object is mutable
     assert(1 == *vi);
     // *vi = 13; // Error: constant-iterator points to an immutable element

     int a[]{3, 1, 4};
     auto ai = std::ranges::cbegin(a); // cbegin works with C-arrays as well
     assert(3 == *ai and *(ai + 1) == 1);
     // *ai = 13; // Error: read-only variable is not assignable
 }

.SH See also

   ranges::begin returns an iterator to the beginning of a range
   (C++20)       (customization point object)
   begin
   cbegin        returns an iterator to the beginning of a container or array
   \fI(C++11)\fP       \fI(function template)\fP
   \fI(C++14)\fP
